Query VAM Xtran

Overview

The queryVamXtran interface enables merchants to query previously applied VAM (Virtual Account Management) accounts by reference number and/or account holder name. At least one of referenceNumber and accountHolderName must be provided. Botim Money returns a list of matching virtual account information.

API URL

• UAT: https://uat.test2pay.com/sgs/api/vam/queryVamXtran
• Production: https://api.payby.com/sgs/api/vam/queryVamXtran

Request

Http Header

Attributes

• Content-Language String
  • The language for the response message. Defaults to English.
  • Example value: en
  • Maximum length: 10
• Content-Type String Required
  • Media type of the request body.
  • Required for operations with a request body.
  • Format: application/json
• sign String Required
  • Request signature using private-key cryptography.
  • Ensures the payment gateway can verify the request origin.
  • Example value: RSA_SIGNATURE_BASE64_STRING
• Partner-Id String Required
  • Unique partner identifier.
  • Example value: 200001200101
  • Maximum length: 12

Http Body

• requestTime Timestamp(3) Required

  • Example value: 1581493898000

• bizContent Object Required

  • referenceNumber String Optional

    • Merchant-defined reference number. Only letters and digits are supported. At least one of referenceNumber and accountHolderName must be provided.
    • Example value: REFQUERY001
    • Maximum length: 64

  • accountHolderName String Optional

    • Account holder name. Encrypted with the merchant's public key (SHA-256). At least one of referenceNumber and accountHolderName must be provided.
    • Maximum length: 75

Request Sample

//Http Header
{
    "Content-Language": "en",
    "Content-Type": "application/json",
    "sign": "aMs582GhLeRv4fL3xqw7nN4dlzWS+ZVzdsNXT6rKwPpj7qOM4Y7qZBP3Yl6HogILy4IyX1tp8M7D92rK37hUgJg814odd1INIuy4l+KTRPA1Y3F8y0hVGXak0ddeVcOM3XNN+YEhvPClBx4EpmfWVqY3A2qNJTo3ugwr6uZiVGA38OjHRLZthGa+5nea0DtLaZYQnOGWaCI6fPIBZ7qr9HTiVkIsAp3N4m4cHR+3Rvpdbzu2TZoScA358D9wGmF5UOkbHCjwNV03I3O8HzaKUqMe4jnXZ+lJ0TMmxmqLrcMyMztJjZMQB9S4lXMW2+TqMrdNgLQv3GLiQ9IFvhUVEg==",
    "Partner-Id": "200000429066"
}

//Http Body
{
  "requestTime": 1581405399656,
  "bizContent": {
    "referenceNumber": "REFQUERY001",
    "accountHolderName": "i0qWVkLjDrPQ1uhnwIs3NgIXUdy2jB1ZKiuB5H5wSmiBJO5bO2r7tHefI54F/aEhKnZ/EXJ8097aVjfWdsD7Vb9rUsBF254vJ2cusy4NVe6OhWv/b9KrkdYh+9FjRK/TXYuZpbu5nnYHX/v5HOxFKBl4iSDBE4D8KtUWb2Zxc1IhlqhDy8Sf1hHCck8LAyeSlxo6p1qyc5SC75BSyPTVm3IDCQhNeE4IGT4WZaMd9LmvChEesOH8CKg9ff+7DNpqkf2Zl0aQjK6/2SNc0+yWf4faNuAHq17GZGadCGs0IyyhHfE9us1xKyDS6hgRBpXY2g0aUFVFa44QUsJVF2VI8Q=="
  }
}

Response

Http Header

sign String Required

When Botim Money sends response, Botim Money will use its own private key to sign the message, and the merchant uses Botim Money 's public key to verify the signature. If the verification is passed, it proves that the response was sent by Botim Money and not faked by others.

Http Body

head

Attributes

applyStatus String Required

The request apply status.

Valid values:

• SUCCESS - Apply successfully
• FAIL - Apply failed
• ERROR - Apply exception

Example value: SUCCESS

Maximum length: 16

code String Required

The response code.

Example value: 0

Maximum length: 10

msg String

The response message.

Maximum length: 200

body

Notice

Body is returned only when applyStatus = SUCCESS and code = 0.

• vamAccountDetails List<VamAccountDetail> Required
  • List of virtual account information.

VamAccountDetail

• iban String Required

  • Virtual account IBAN. Returned encrypted with the merchant's public key (SHA-256).

• accountNo String Required

  • Virtual account number.
  • Example value: 600001603

• referenceNumber String Required

  • Merchant-defined reference number.
  • Example value: REFQUERY001

• swiftCode String Required

  • Bank SWIFT/BIC code.
  • Example value: BBMEAEADXXX

• bankAddress String

  • Bank address.
  • Example value: Abu Dhabi, UAE

• accountStatus String Required

  • Virtual account status.
  • Possible values: Init, Processing, Valid, Closed, Failed
  • Example value: Valid

• accountHolder String Required

  • Account holder name. Returned encrypted with the merchant's public key (SHA-256).

• bankName String Required

  • Bank name.
  • Example value: Mashreq Bank

Response Sample

//Http Header
{
  "sign": "nDdClX1tAyV3qcX/Epay6AXFNRGSsWd8ysWO9SgwPrNTetSePLA9C39mGp6qRbjJeqXLEnYLwSkBu5eKdtyVX3tflGLiV2kvRjVfYpTCjXdVL2Pcnv2w+ghjHe2jL988iklk7q5AjAgdtXNphpHcTes9pk6W3bVCbvijH6at0fExUtZ91L1LrnPGELT1IJm/lFW3w4KLh0Gxs7FzDPI9RDfUemObNlRzV8kCtkWahwPgs/hBnS69GyYDKN7ihQX2UiLuP239wl6IA+VG/ZZKHPhLs8bbuOS+LKWORIp6jRt+JsAx7c/Ot1RNyOnHKxPRKJ8bVTohEp39yUz/HwG8oA=="
}

//Http Body
{
  "head": {
    "applyStatus": "SUCCESS",
    "code": "0",
    "msg": "SUCCESS"
  },
  "body": {
    "vamAccountDetails": [
      {
        "iban": "SgsiXi2T//eEymXADGbK7o0EE9wmCTQxi4gLNp7y1JYTW0PbGbEmYk2rmsLc56kSOMbgAGUPf0Na0qs3uPwwhyfGSrHJsxNB8J2wBhcvBm8eSX2BjS45qT/hI8pW2KhpprWVXMmwCCh7NX36Imp0WcsDg8o4EHKBKgg1GLBOBkCh7tHAEDMPhwOllsGYioPb9eKmXHoRlgBAosD+wgEayvLS2LgGb18gGMM3w4ujwLKllQ2g2cr3HiCzvEcaroiBJ/1XSjGQ5rJNVomLpXec05Mr9Ql2oszh8uGbayCL3M4EhppXsA0KTYkHhxmZ5yM7pWmpHQH2tRtxE8EM5j7o3g==",
        "accountNo": "600001603",
        "referenceNumber": "REFQUERY001",
        "swiftCode": "BBMEAEADXXX",
        "bankAddress": "Abu Dhabi, UAE",
        "accountStatus": "Valid",
        "accountHolder": "SgsiXi2T//eEymXADGbK7o0EE9wmCTQxi4gLNp7y1JYTW0PbGbEmYk2rmsLc56kSOMbgAGUPf0Na0qs3uPwwhyfGSrHJsxNB8J2wBhcvBm8eSX2BjS45qT/hI8pW2KhpprWVXMmwCCh7NX36Imp0WcsDg8o4EHKBKgg1GLBOBkCh7tHAEDMPhwOllsGYioPb9eKmXHoRlgBAosD+wgEayvLS2LgGb18gGMM3w4ujwLKllQ2g2cr3HiCzvEcaroiBJ/1XSjGQ5rJNVomLpXec05Mr9Ql2oszh8uGbayCL3M4EhppXsA0KTYkHhxmZ5yM7pWmpHQH2tRtxE8EM5j7o3g==",
        "bankName": "Mashreq Bank"
      }
    ]
  }
}

Response Codes

Code	Message	Cause	Workaround
0	SUCCESS	Success
400	INVALID_PARAMETER	Invalid parameters, for example both referenceNumber and accountHolderName are empty	Adjust request parameters
402	RATE_LIMIT_REJECT	Too many requests	Reduce request frequency
403	UNAUTHORIZED	API not authorized, signature error, or KYC not passed	Contact Botim Money
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact Botim Money
500	SYSTEM_ERROR	System error	Contact Botim Money, or try again later
504	SERVICE_TIMEOUT	Service timeout	Try again later
62004	MERCHANT_ORDER_NO_NOT_EXIST	No virtual account record found for the given reference number	Adjust request parameters
62101	WRONG_IBAN_FORMAT	IBAN is empty or incorrectly formatted	Contact Botim Money
62102	IBAN_NOT_FOUND	IBAN not found	Contact Botim Money
62118	INVALID_RESPONSE	Invalid response returned by the channel	Contact Botim Money, or try again later